<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>[Generic Component Framework v3] GCF Content XML File Specification</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<!--link href="tabs.css" rel="stylesheet" type="text/css"-->
</head><body>
 <div id="wrapper">
    <div id="logo_box">
        <a class="img_link" href="https://github.com/pnudupa/gcf" target="_blank" ><img style="float:left;margin-left:10px;margin-top:5px;margin-bottom:5px;"src="header_gcf_logo.jpg" alt="GCF LOGO"/></a>
        <a class="img_link" href="https://www.vcreatelogic.com/" target="_blank" ><img style="float:right;margin-right:10px; margin-top: 30px;" src="header_vcl_logo.jpg" alt="VCL LOGO"/></a>
        <div style="clear:both"></div>
    </div>
    <div class="nav">
        <ul>
            <li class="selectedpage">
                <a class="a-home" href="index.html" >
                    <span>Home</span>
                </a>
            </li>
            <li>
                <a class="a-classes " href="classes.html">
                    <span>All Classes</span>
                </a>
            </li>
            <li>
                <a class="a-home " href="gcf_modules.html">
                    <span>Modules</span>
                </a>
            </li>
            <li>
                <a class="a-home " href="gcf_guides_and_videos.html">
                    <span>Guides & Videos</span>
                </a>
            </li>
            <li>
                <a class="a-home " href="gcf_tools_and_inbuilt_components.html">
                    <span>Tools & Components</span>
                </a>
            </li>
        </ul>
    </div>
    <div id="main-content">
        <div class="inside">
        <div>
<!-- Generated by Doxygen 1.8.16 -->
</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">GCF Content XML File Specification </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#gcf_content_xml_1">Element hierarchy</a></li>
<li class="level1"><a href="#gcf_content_xml_2">content XML element</a></li>
<li class="level1"><a href="#gcf_content_xml_3">object XML element</a><ul><li class="level2"><a href="#gcf_content_xml_31">parent attribute</a></li>
<li class="level2"><a href="#gcf_content_xml_32">allowmetaaccess attribute</a></li>
</ul>
</li>
<li class="level1"><a href="#gcf_content_xml_4">property XML element</a></li>
<li class="level1"><a href="#gcf_content_xml_5">connection XML element</a></li>
</ul>
</div>
<div class="textblock"><p>Components can offer a content file for loading while handling the pre-content-load event in <a class="el" href="class_g_c_f_1_1_component.html#a7b9e7071c2f4b483a4ee51b08b70835c">GCF::Component::contentLoadEvent()</a>. The content file is a XML file whose primary purpose is to provide a list of objects that need to be loaded during <a class="el" href="class_g_c_f_1_1_component.html#a06e3573f06292a5211b81201ced61deb">GCF::Component::load()</a>. A typical content file would look like this</p>
<pre class="fragment">&lt;content&gt;

    &lt;object name="a" /&gt;
    &lt;object name="b" /&gt;
    &lt;object name="c" /&gt;
    &lt;object name="d" /&gt;

&lt;/content&gt;
</pre><p>Basically the content-file contains <code>content</code> XML element as root and a series of <code>object</code> XML elements. Each <code>object</code> XML element must have a name attribute, otherwise it is ignored by GCF. Object names must be unique within the component, otherwise GCF will attempt to make it unique by adding some characters at the end of the name.</p>
<p>The <code>object</code> XML element can contain additional attributes, some of which have implicit meanings. This page provides the complete file specification of a content-xml file.</p>
<h1><a class="anchor" id="gcf_content_xml_1"></a>
Element hierarchy</h1>
<p>The content XML file accepts the following element hierarchy</p>
<ul>
<li>content<ul>
<li>object<ul>
<li>property</li>
<li>connection</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>Attributes of all XML elements are case-insensitive. GCF converts attribute names to lower case after parsing the XML file.</p>
<h1><a class="anchor" id="gcf_content_xml_2"></a>
content XML element</h1>
<p>The <code>content</code> XML element is the root of all elements in a content-xml file. This XML element has no attributes of interest. Any attribute specified for this XML element will be left ignored. There should be only one <code>content</code> XML element in a content-file.</p>
<h1><a class="anchor" id="gcf_content_xml_3"></a>
object XML element</h1>
<p><code>object</code> XML element is a direct child of the <code>content</code> XML element. Each <code>object</code> XML element declares the existence of one single named object in the component. The <code>object</code> XML element can have any number of attribtues. Attribute names are case-insensitive. But values are not.</p>
<p>One attribute that MUST be mentioned in the <code>object</code> XML element is the <code>name</code> attribute. This attribute's value must be a unique name within the component, or atleast the content-xml file.</p>
<p>When GCF processes the <code>object</code> XML element, it sends a <a class="el" href="class_g_c_f_1_1_content_object_load_event.html">GCF::ContentObjectLoadEvent</a> to the component. Along with this event GCF will send the value of the <code>name</code> attribute and a key=value map of all other attributes in the <code>object</code> XML element. This map will have all its keys in lower-case letters.</p>
<p>The GCF::ContentObjectLoadEvent::name() function will return the value of the <code>name</code> attribute in the <code>object</code> XML element. The <a class="el" href="class_g_c_f_1_1_content_object_load_event.html#adb2609b60cbd7beb86f426111a0fb262">GCF::ContentObjectLoadEvent::info()</a> function will return a <code>QVariantMap</code> of key=value pairs. Each pair is a attribute=value pair in the <code>object</code> XML element. [<b>NOTE:</b> values for attributes <code>name</code> and <code>parent</code> will not be available from <a class="el" href="class_g_c_f_1_1_content_object_load_event.html#adb2609b60cbd7beb86f426111a0fb262">info()</a>]</p>
<p>A component can handle this event in its <a class="el" href="class_g_c_f_1_1_component.html#a8447de04766d75220159e9db2ceeb5c8">GCF::Component::contentObjectLoadEvent()</a> implementation to </p><ul>
<li>actually load the object (as a <code>QObject</code> instance) </li>
<li>Use the <a class="el" href="class_g_c_f_1_1_content_object_load_event.html#ac1016669478dc3d263622aa5cefa70bf">GCF::ContentObjectLoadEvent::setObject()</a> method on the event object, passed as parameter to the event handler, to send back pointer to the <code>QObject</code> that was just loaded</li>
</ul>
<p>In GCF, we have three major component classes: <a class="el" href="class_g_c_f_1_1_component.html">GCF::Component</a>, <a class="el" href="class_g_c_f_1_1_qml_component.html">GCF::QmlComponent</a> and <a class="el" href="class_g_c_f_1_1_gui_component.html">GCF::GuiComponent</a>. Each of these classes have their own implementation of GCF::Component:contentObjectLoadEvent() "contentObjectLoadEvent()".</p>
<ul>
<li>The <a class="el" href="class_g_c_f_1_1_component.html#a8447de04766d75220159e9db2ceeb5c8">contentObjectLoadEvent()</a> function implementation in <a class="el" href="class_g_c_f_1_1_component.html">GCF::Component</a> simply request for <a class="el" href="class_g_c_f_1_1_component.html#aa764b26829ba318385b3921bf2b1800a">loadObject()</a> to load a named object and returns a pointer to that via <a class="el" href="class_g_c_f_1_1_content_object_load_event.html#ac1016669478dc3d263622aa5cefa70bf">setObject()</a> method.</li>
</ul>
<ul>
<li>The <a class="el" href="class_g_c_f_1_1_gui_component.html#ada64bbc4fc1f124812e60a20bf3ac566">contentObjectLoadEvent()</a> function implementation in <a class="el" href="class_g_c_f_1_1_gui_component.html">GCF::GuiComponent</a> looks for value of the <code>type</code> attribute.<ul>
<li>If type is <code>"widget"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#abede43b20eb5ed489fa73f4727311527">loadWidget()</a> virtual function to create a <code>QWidget</code>.</li>
<li>If type is <code>"action"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#ab4ee527d9f6a3d0d24b67055a57bf8d2">loadAction()</a> virtual function to create a <code>QAction</code>.</li>
<li>If type is <code>"menu"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#a6ec17f7013f1a5403811aedc1a44bccd">loadMenu()</a> virtual function to create a <code>QMenu</code>.</li>
<li>If type is <code>"actiongroup"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#ab7006855f079d3023da4240d33114b19">loadActionGroup()</a> virtual function to create a <code>QActionGroup</code>.</li>
<li>If type is <code>"toolbar"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#aadef90f4c5c51035fa954642a1cb539c">loadToolBar()</a> virtual function to create a <code>QToolBar</code>.</li>
<li>If type is <code>"menubar"</code> then it invokes the <a class="el" href="class_g_c_f_1_1_gui_component.html#af29be55061f29a43ed2f8196851ea19d">loadMenuBar()</a> virtual function to create a <code>QMenuBar</code>.</li>
<li>For all other types, <a class="el" href="class_g_c_f_1_1_component.html#a8447de04766d75220159e9db2ceeb5c8">GCF::Component::contentObjectLoadEvent()</a> is called. Which in-turn calls <a class="el" href="class_g_c_f_1_1_component.html#aa764b26829ba318385b3921bf2b1800a">loadObject()</a></li>
</ul>
</li>
</ul>
<ul>
<li>The <a class="el" href="class_g_c_f_1_1_qml_component.html#a4369fecfd2a15454b5910aedb26f468e">contentObjectLoadEvent()</a> function implementation in <a class="el" href="class_g_c_f_1_1_qml_component.html">GCF::QmlComponent</a> looks for value of the <code>type</code> attribute. If the value of the type attribute is <code>"qml"</code> then, it looks for the value of the <code>url</code> attribute. The class then loads a .qml file available at the URL specified in the <code>url</code> attribute. The URL attribute could contain a .qml file URL for loading from<ul>
<li>a HTTP location. Example: <a href="http://something.com/folder/MyCoolItem.qml">http://something.com/folder/MyCoolItem.qml</a></li>
<li>a FTP location. Example: <a href="ftp://something.com/folder/MyCoolItem.qml">ftp://something.com/folder/MyCoolItem.qml</a></li>
<li>local file system<ul>
<li>Example: <a href="file:///Users/username/folder/MyCoolItem.qml">file:///Users/username/folder/MyCoolItem.qml</a></li>
<li>Example: ../../folder/MyCoolItem.qml</li>
</ul>
</li>
<li>a QRC location. Example: qrc://Folder/MyCoolItem.qml</li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="gcf_content_xml_31"></a>
parent attribute</h2>
<p>After the <a class="el" href="class_g_c_f_1_1_component.html#a8447de04766d75220159e9db2ceeb5c8">GCF::Component::contentObjectLoadEvent()</a> returns, GCF looks for value of the <code>parent</code> attribute in the <code>object</code> XML element. The value of <code>parent</code> attribute has to be a path to an already registered object in the application. If the <code>path</code> corresponds to an object owned by another component, then a <a class="el" href="class_g_c_f_1_1_content_object_merge_event.html">GCF::ContentObjectMergeEvent</a> is sent to that component. This event can be handled in the <a class="el" href="class_g_c_f_1_1_component.html#a1de83ead9a736b7fe19f61626b24a5b6">GCF::Component::contentObjectMergeEvent()</a> to perform object-merging. Components can customize the way in which merging happens.</p>
<ul>
<li>The <a class="el" href="class_g_c_f_1_1_component.html#a1de83ead9a736b7fe19f61626b24a5b6">contentObjectMergeEvent()</a> implementation in <a class="el" href="class_g_c_f_1_1_component.html">GCF::Component</a> class simply makes use of the <code>QObject::setParent()</code> method to merge child into parent.</li>
</ul>
<ul>
<li>The <a class="el" href="class_g_c_f_1_1_gui_component.html#a862fb78fdba64b956eab4c8a82c89b07">contentObjectMergeEvent</a> implementation in <a class="el" href="class_g_c_f_1_1_gui_component.html">GCF::GuiComponent</a> class looks for the <code>type</code> attribute associated with the parent and takes an appropriate action.<ul>
<li>if parent type is <code>widget</code> - <a class="el" href="class_g_c_f_1_1_gui_component.html#a7e77aa7032803aacbe8a695f15121760">mergeWithWidget()</a> is called. Note if the child is not a widget, then <a class="el" href="class_g_c_f_1_1_component.html#a1de83ead9a736b7fe19f61626b24a5b6">contentObjectMergeEvent</a> is called.</li>
<li>if parent type is <code>actiongroup</code> - <a class="el" href="class_g_c_f_1_1_gui_component.html#a06b9c46dd5bc98a483ceefcd010da43a">mergeWithActionGroup()</a>. Note if the child is not a <code>QAction</code>, then <a class="el" href="class_g_c_f_1_1_component.html#a1de83ead9a736b7fe19f61626b24a5b6">contentObjectMergeEvent()</a> is called.</li>
<li>if parent type is <code>menu</code> - <a class="el" href="class_g_c_f_1_1_gui_component.html#a64ce09eb669f5a3ff946194d950e797f">mergeWithMenu()</a> is called.</li>
<li>if parent type is <code>toolbar</code> - <a class="el" href="class_g_c_f_1_1_gui_component.html#ad8b0b899c654a6e51d7905f429700de5">mergeWithToolBar()</a> is called.</li>
<li>if parent type is <code>menubar</code> - <a class="el" href="class_g_c_f_1_1_gui_component.html#a24fcf14ba83e79f7c2afe024c3b0fd8b">mergeWithMenuBar()</a> is called.</li>
</ul>
</li>
</ul>
<ul>
<li><a class="el" href="class_g_c_f_1_1_qml_component.html">GCF::QmlComponent</a>'s implementation of <code>contentObjectMergeEvent()</code> ignores merging between two QML objects. This means that if the <code>type</code> attribute of both parent and child is <code>"qml"</code>, then the merging is ignored.</li>
</ul>
<h2><a class="anchor" id="gcf_content_xml_32"></a>
allowmetaaccess attribute</h2>
<p>Each <code>object</code> XML element can have an optional <code>allowMetaAccess</code> attribute. This attribute can have a value of <code>"true"</code> or <code>"false"</code>. If no such attribute is specified, then the value is assumed to be <code>"false"</code> by default.</p>
<p>The value of this attribute is checked when a method or property on this object is accessed during an IPC call. If the value of this attribute is <code>"false"</code>, then the IPC call will be aborted.</p>
<p>Read <a class="el" href="group__gcf__ipc.html">IPC module in GCF</a> for more information on IPC.</p>
<h1><a class="anchor" id="gcf_content_xml_4"></a>
property XML element</h1>
<p>The <code>property</code> XML element can be used to set the property of an object upon its creation and it can have the following child XML elements.</p>
<ul>
<li><code>key</code> </li>
<li><code>value</code> </li>
</ul>
<p>The <code>key</code> XML element should contain name of the property that needs to be set. The <code>value</code> XML element should contain the value of the property that needs to be set. You can use this to set <code>int</code>, <code>bool</code>, <code>double</code>, <code>QString</code>, and <code>QByteArray</code> properties only.</p>
<p>Example:</p>
<pre class="fragment">&lt;content&gt;

    &lt;object name="window"&gt;
        &lt;property&gt;
            &lt;key&gt;windowTitle&lt;/key&gt;
            &lt;value&gt;title string for the window&lt;/value&gt;
        &lt;/property&gt;
    &lt;/object&gt;

&lt;/content&gt;
</pre><h1><a class="anchor" id="gcf_content_xml_5"></a>
connection XML element</h1>
<p>The <code>connection</code> XML element can be used to establish a signal slot connection between the object in question and any other object in the application. The rule here is that either the sending signal or the receiving slot/member MUST belong to the object in question. You cannot use the <code>connection</code> XML element to establish signal/slot connections between two random objects.</p>
<p>The <code>connection</code> XML element can have the following child XML elements.</p>
<ul>
<li><code>sender</code> </li>
<li><code>receiver</code> </li>
</ul>
<p>The text specified for either <code>sender</code> or <code>receiver</code> XML element can be in the following format</p>
<p> 
<pre>
{Component}.{Object}::{MemberSignature}
</pre>
</p>
<ul>
<li>if {Component} is not specified, then the object is considered to be from this component.</li>
</ul>
<ul>
<li>if both {Component} and {Object} are not specified, then the method is considered to belong to the object in question (referred to by the enclosing <code>object</code> XML)</li>
</ul>
<p>Example:</p>
<pre class="fragment">&lt;content&gt;

    &lt;object name="CalendarWidget"
            parent="Application.BaseComponent.Window"&gt;

        &lt;connection&gt;
            &lt;sender&gt;clicked(QDate)&lt;/sender&gt;
            &lt;receiver&gt;Application.DateEdit.DateEditWidget::setDate(QDate)&lt;/receiver&gt;
        &lt;/connection&gt;

        &lt;connection&gt;
            &lt;sender&gt;Application.DateEdit.DateEditWidget::dateChanged(QDate)&lt;/sender&gt;
            &lt;receiver&gt;setSelectedDate(QDate)&lt;/receiver&gt;
        &lt;/connection&gt;

    &lt;/object&gt;

&lt;/content&gt;
</pre> </div></div><!-- contents -->
</div><!-- PageDoc -->
</div>
</div>
</div>
<div class="footer_content">
<table width="100%" class="footer">
<tr>
<td align="left" width="50%">Copyright &copy; 2013-2019,
 <a class="el" href="http://www.vcreatelogic.com" target="_black">VCreate Logic Private Limited</a></td>
<td align="right" width="50%"><a class="el" href="http://www.vcreatelogic.com/products/gcf" target="_black">GCF - Generic Component Framework</a></td>
</tr>
</table>
</div>
</div>
</body>
</html>
